ποΈGitΠ―ΡΠ°ποΈ
docs/README.md fix/qr-error-correction (7b45f84f) Text, 4.69 KB
Documentation Structure
This directory contains the source documentation for the Meshtastic Android/Desktop/iOS app.
It serves three consumers:
1. In-app docs browser β bundled via Compose Resources at build time
2. Jekyll site β GitHub Pages (this directory is the Jekyll source root)
3. meshtastic.org β Docusaurus sync (upstream consumption)
Locale Layout
T282828
docs/
βββ _config.yml, _data/, _layouts/, _sass/ β Jekyll site infrastructure
βββ en/ β English source (edit here)
β βββ user/ β User Guide pages
β βββ developer/ β Developer Guide pages
β βββ index.md β Site home page
β βββ user.md β User Guide nav parent
β βββ developer.md β Developer Guide nav parent
βββ fr-rFR/ β French (Crowdin-generated)
β βββ user/ β Translated user guide
βββ de-rDE/ β German (Crowdin-generated)
β βββ user/
βββ ... β Other locales
Editing Guidelines
β’ English source: Edit files under T383838docs/en/. These are the authoritative source.
β’ Translations: Do not edit files in locale folders directly. They are auto-generated
by Crowdin and will be overwritten on sync.
Contribute translations via Crowdin instead.
β’ Adding a page: Create the T383838.md file in T383838docs/en/user/ or T383838docs/en/developer/, then
register it in T383838feature/docs/.../DocBundleLoader.kt for in-app bundling.
How Translations Work
1. English source files (T383838docs/en/user/*.md) are uploaded to Crowdin as translation sources
2. Volunteers translate via the Crowdin web UI
3. Crowdin PRs land translated files at T383838docs/{android_code}/user/*.md (e.g., T383838fr-rFR, T383838pt-rBR)
4. At build time, the Gradle T383838syncTranslatedDocsToComposeResources task bundles them into
locale-qualified Compose Resources for the in-app reader
5. The in-app T383838DocBundleLoader tries the user's locale first, then falls back to English
Publishing & Versioning
The GitHub Pages site is published to the persistent T383838gh-pages branch as parallel
channels (GitHub Pages must be configured to serve from that branch):
βββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββ
β Path β Content β Published by β
βββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββ€
β T383838/ β Latest production release (defaβ¦ β T383838docs-release.yml on T383838vX.Y.Z tags β
β T383838/vX.Y.Z/ β Permanent per-release copy β T383838docs-release.yml on T383838vX.Y.Z tags β
β T383838/vX.Y.Z-open.N/ β Per-tag open-testing snapshot β T383838docs-release.yml on T383838vX.Y.Z-open.N tags β
β T383838/vX.Y.Z-closed.N/ β Per-tag closed-testing snapshot β T383838docs-release.yml on T383838vX.Y.Z-closed.N tags β
β T383838/main/ β Snapshot of the T383838main branch β T383838docs-deploy.yml on pushes to T383838main β
β T383838/api/ β Dokka API reference β T383838docs-deploy.yml, plus production releases β
β T383838/versions.json β Version manifest for the site'sβ¦ β regenerated on every deploy β
βββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββ
T383838-internal.N tags are deliberately not published β they are cut many times per
cycle and are not a documented channel.
Prerelease snapshots accumulate during a version cycle so testers can read the
docs for the exact build they are running. Once the production T383838vX.Y.Z tag
ships, T383838/vX.Y.Z/ supersedes them and Post-Release Cleanup (run with
T383838base_version=X.Y.Z) reaps the T383838vX.Y.Z-open.* / T383838vX.Y.Z-closed.* directories
along with the prerelease tags. That workflow defaults to a dry run.
Only production releases own T383838/ and rebuild T383838/api/. Prerelease tags publish
their own directory only: T383838/api/ is unversioned and already refreshed by every
push to T383838main, so rebuilding Dokka (~14 min) per prerelease tag would cost far
more than it refreshes. Until a production release exists, T383838/ redirects to the
best available channel β newest open, then newest closed, then T383838/main/ β and
upgrades automatically as better channels appear. Real release content at the
root is never overwritten by that fallback.
Each deploy overlays only its own channels via T383838scripts/docs/publish-to-gh-pages.sh,
so release history accumulates instead of being wiped by the next deploy. The header
version dropdown (T383838_includes/version_switcher.html) reads T383838/versions.json at runtime;
a separate header link points to the upstream docs at meshtastic.org. To backfill a
release (e.g. after first enabling this), run the "Docs Release" workflow manually
against the release tag.
Served by rngit 1.5.0 - Generated in 0.04s